Crate tor_keymgr
source ·Expand description
§tor-keymgr
Code to fetch, store, and update keys.
§Overview
This crate is part of Arti, a project to implement Tor in Rust.
§Likely to change
The APIs exposed by this crate (even without the keymgr
feature)
are new and are likely to change rapidly.
We’ll therefore often be making semver-breaking changes
(and will update the crate version accordingly).
§Key stores
The KeyMgr
is an interface to one or more key stores. A key
store is a type that implements the Keystore
trait.
The following key store implementations are provided:
ArtiNativeKeystore
: an on-disk store that stores keys in OpenSSH format. It does not currently support keys that have a passphrase. Passphrase support will be added in the future (see #902).- (not yet implemented) C Tor key store: an on-disk store that is backwards-compatible with C Tor (new keys are stored in the format used by C Tor, and any existing keys are expected to be in this format too).
In the future we plan to also support HSM-based key stores.
§Key specifiers and key types
The Keystore
APIs identify a particular instance of a key using a
KeySpecifier
and a KeyType
.
This enables key stores to have multiple keys with the same role
(i.e. the same KeySpecifier::arti_path
), but different key types (i.e.
different KeyType::arti_extension
s).
A KeySpecifier
identifies a group of equivalent keys, each of a different
type (algorithm). In the ArtiNativeKeystore
, it is used to determine the
path of the key within the key store, minus the extension (the extension of
the key is derived from its KeyType
). KeySpecifier
implementers must
specify:
- the
ArtiPath
of the specifier: this serves as a unique identifier for a particular instance of a key, and is used byArtiNativeKeystore
to determine the path of a key on disk - the
CTorPath
of the key: the location of the key in the C Tor key store (optional).
KeyType
represents the type (“keypair”, “public key”) and
algorithm (“ed25519”, “x25519”) of a key
KeyType::arti_extension
specifies what file extension keys of that type are
expected to have when stored in an ArtiNativeKeystore
: ArtiNativeKeystore
s
join the KeySpecifier::arti_path
and KeyType::arti_extension
to form the
path of the key on disk (relative to the root directory of the key store).
§Feature flags
§Additive features
keymgr
– build with full key manager support. Disabling this feature causestor-keymgr
to export a no-op, placeholder implementation.
§Experimental and unstable features
Note that the APIs enabled by these features are NOT covered by semantic versioning1 guarantees: we might break them or remove them between patch versions.
- (None at present)
Remember, semantic versioning is what makes various
cargo
features work reliably. To be explicit: if you wantcargo update
to only make safe changes, then you cannot enable these features. ↩
Re-exports§
pub use ssh_key;
keymgr
Modules§
- Keystore configuration.
- test_utils
testing
Test helpers.
Macros§
- A helper for implementing
KeySpecifier
s. - Register a
KeyPathInfoExtractor
for use withKeyMgr
.
Structs§
- ArtiEphemeralKeystore
keymgr
The Ephemeral Arti key store - ArtiNativeKeystore
keymgr
The Arti key store. - A unique identifier for a particular instance of a key.
- The path of a key in the C Tor key store.
- KeyMgr
keymgr
- KeyMgrBuilder
keymgr
Builder forKeyMgr
. - Information about a
KeyPath
. - Builder for
KeyPathInfo
. - A range specifying a substring of a
KeyPath
. - KeystoreEntry
keymgr
A keystore entry descriptor. - An identifier for a particular
Keystore
instance. - UnknownKeyTypeError
keymgr
An error that happens when we encounter an unknown key type.
Enums§
- An error caused by a syntactically invalid
ArtiPath
. - An error returned by a
KeySpecifier
. - An Error type for this crate.
- Error to be returned by
KeySpecifierComponent::from_slug
implementations - KeyMgrBuilderError
keymgr
Error type for KeyMgrBuilder - The identifier of a key.
- An error while attempting to extract information about a key given its path
- KeyType
keymgr
A type of key stored in the key store. - An error caused by keystore corruption.
- Specifies which keystores a
KeyMgr
operation should apply to. - SshKeyData
keymgr
A public key or a keypair.
Constants§
- A separator for that marks the beginning of the keys denotators within an
ArtiPath
.
Traits§
- EncodableKey
keymgr
A key that can be serialized to, and deserialized from, a format used by aKeystore
. - A trait for extracting info out of a
KeyPath
s. - The “specifier” of a key, which identifies an instance of a key.
- A trait for serializing and deserializing specific types of
Slug
s. - A pattern specifying some or all of a kind of key
- Keygen
keymgr
A trait for generating fresh keys. - KeygenRng
keymgr
A random number generator for generatingEncodableKey
s. - Keystore
keymgr
A generic key store. - An error returned by a
Keystore
. - ToEncodableKey
keymgr
A key that can be converted to anEncodableKey
.